---
title: "Date Filter"
---

Date Filters allow you to filter date data.

{% imageCaption imagePath="resources/date-filter.png" alt="Date Filter" centered=true /%}

## Enabling Date Filters

{% gridExampleRunner title="Date Filter" name="date-filter" /%}

The Date Filter is the default filter used in AG Grid Community for columns with date [Cell Data Type](./cell-data-types/), but it can also be explicitly configured as shown below:

```{% frameworkTransform=true %}
const gridOptions = {
    columnDefs: [
        {
            field: 'startDate',
            // Date Filter is used by default in Community version for date columns
            filter: true,
            filterParams: {
                // pass in additional parameters to the Date Filter
            },
        },
        {
            field: 'endDate',
            // explicitly configure column to use the Date Filter
            filter: 'agDateColumnFilter',
            filterParams: {
                // pass in additional parameters to the Date Filter
            },
        },
    ],
}
```

## Date Filter Parameters

Date Filters are configured though the `filterParams` attribute of the column definition (`IDateFilterParams` interface):

{% interfaceDocumentation interfaceName="IDateFilterParams" overrideSrc="filter-date/date-filter-params.json" config={"description":"", "sortAlphabetically":true} /%}

## Date Range

The example below demonstrates configuring date range filtering in the Date Filter with minimum and maximum validation dates:

* For the **Start Date** column:
  * The `minValidDate` parameter is set to `'2000-01-01'` using a string.
  * The `maxValidDate` is dynamically set to tomorrow's date using a `Date` object.
* For the **End Date** column:
  * The `minValidYear` parameter is set to `2010`.
  * The `maxValidYear` parameter is set to `2030`.
* Dates outside the valid ranges will be invalid.

{% gridExampleRunner title="Setting Date Range For Filter" name="range-for-date-filter"  exampleHeight=520 /%}

## Filter Comparator

Dates can be represented in your data in many ways e.g. as a JavaScript `Date` object, as a string in a particular format such as `'26-MAR-2020'`, or something else. How you represent dates will be particular to your application.

The Date Filter will automatically be configured to work correctly if the [Cell Data Type](./cell-data-types/) is `date`, `dateString`, `dateTime` or `dateTimeString`.

{% note %}
If using `Date` objects, the default date comparator assumes that the `Date`s do not have a time (e.g. they are at midnight local time). If your dates have times, then you will either need to override the [Filter Values](#filter-values) to remove the time, to switch cell data type to `dateTime`, or provide a `comparator` that can handle the time.
{% /note %}

If you are not using Cell Data Types (and the cell value is not a `Date` object, which will also work automatically), then a `comparator` needs to be configured to allow the Date Filter to perform the date comparisons.

{% interfaceDocumentation interfaceName="IDateFilterParams" names=["comparator"] config={"description":"", "overrideBottomMargin":"1rem"} /%}

The `comparator` function takes two parameters. The first parameter is a JavaScript `Date` object for the selected date in the filter (with the time set to midnight). The second parameter is the current value of the cell in the row being evaluated. The function must return:

* Any number < 0 if the cell value is less than the filter date.
* 0 if the dates are the same.
* Any number > 0 if the cell value is greater than the filter date.

This pattern is intended to be similar to the JavaScript `compareTo(a, b)` function.

A date filter with a comparator can be configured similar to the following:

```{% frameworkTransform=true %}
const gridOptions = {
    columnDefs: [
        // column definition configured to use a date filter
        {
            field: 'date',
            filter: 'agDateColumnFilter',
            // add extra parameters for the date filter
            filterParams: {
                // provide comparator function
                comparator: (filterLocalDateAtMidnight, cellValue) => {
                    const dateAsString = cellValue;

                    if (dateAsString == null) {
                        return 0;
                    }

                    // In the example application, dates are stored as dd/mm/yyyy
                    // We create a Date object for comparison against the filter date
                    const dateParts = dateAsString.split('/');
                    const year = Number(dateParts[2]);
                    const month = Number(dateParts[1]) - 1;
                    const day = Number(dateParts[0]);
                    const cellDate = new Date(year, month, day);

                    // Now that both parameters are Date objects, we can compare
                    if (cellDate < filterLocalDateAtMidnight) {
                        return -1;
                    } else if (cellDate > filterLocalDateAtMidnight) {
                        return 1;
                    }
                    return 0;
                }
            }
        }
    ]
}
```

Once the date comparator callback is provided, then the Date Filter is able to perform all the comparison operations it needs, e.g. 'Less Than', 'Greater Than' and 'Equals'.

If the cell values can contain invalid dates, then the `isValidDate` filter param should be implemented alongside `comparator` to allow the invalid date values to be filtered out.

The example below demonstrates configuring a comparator:

{% gridExampleRunner title="Date Filter Comparator" name="date-filter-comparator" /%}

## Filter Model

The Filter Model describes the current state of the applied Date Filter. The Date Filter Model represents the Date as a string in format `'YYYY-MM-DD'`, however when doing comparisons the date is provided as a JavaScript `Date` object as that's what date pickers typically work with. The model uses string representation to make it easier to save and avoid any timezone issues.

If only one [Filter Condition](./filter-conditions/) is set, this will be a `DateFilterModel`:

{% interfaceDocumentation interfaceName="DateFilterModel" config={"description":""} /%}

If more than one Filter Condition is set, then multiple instances of the model are created and wrapped inside a Combined Model (`ICombinedSimpleModel<DateFilterModel>`). A Combined Model looks as follows:

```ts
// A filter combining multiple conditions
interface ICombinedSimpleModel<DateFilterModel> {
    filterType: string;

    operator: JoinOperator;

    // multiple instances of the Filter Model
    conditions: DateFilterModel[];
}

type JoinOperator = 'AND' | 'OR';
```

Note that in AG Grid versions prior to 29.2, only two Filter Conditions were supported. These appeared in the Combined Model as properties `condition1` and `condition2`. The grid will still accept and supply models using these properties, but this behaviour is deprecated. The `conditions` property should be used instead.

An example of a Filter Model with two conditions is as follows:

```js
// Date Filter with two conditions, both are equals type
const dateEquals04OrEquals08 = {
    filterType: 'date',
    operator: 'OR',
    conditions: [
        {
            filterType: 'date',
            type: 'equals',
            dateFrom: '2004-08-29'
        },
        {
            filterType: 'date',
            type: 'equals',
            dateFrom: '2008-08-24'
        }
    ]
};
```

## Filter Options

The Date Filter presents a list of [Filter Options](./filter-conditions/#filter-options) to the user.

The list of options is as follows:

| Option Name             | Option Key            | Included by Default |
| ----------------------- | --------------------- | ------------------- |
| Equals                  | `equals`              | Yes                 |
| Does not equal          | `notEqual`            | Yes                 |
| Before                  | `lessThan`            | Yes                 |
| After                   | `greaterThan`         | Yes                 |
| Between                 | `inRange`             | Yes                 |
| Blank                   | `blank`               | Yes                 |
| Not blank               | `notBlank`            | Yes                 |
| Choose one              | `empty`               | No                  |

Note that the `empty` filter option is primarily used when creating [Custom Filter Options](./filter-conditions/#custom-filter-options). When 'Choose one' is displayed, the filter is not active.

The default option for the Date Filter is `equals`.

When providing filter options, the default filter option (or the first option if no default set) must be an option that displays an input or the `empty` filter option (as a filter option with no inputs would mean the filter is active by default).

## Range Input Validation and Error States

When using the `inRange` filter type, the grid performs input validation to ensure the bounds of the range produce a valid filter; that is, where the start date is earlier than the end date.

Where this is not the case, the last edited input will display a red border and a hover tooltip directing the user to enter a valid date. While the filter is in an invalid state, the filter will not be applied.
Screen readers that respond to the `aria-invalid` attribute or the `ValidityState` of the input will detect the input as invalid.

## Filter Values

By default, the values supplied to the Date Filter are retrieved from the data based on the `field` attribute. This can be overridden by providing a `filterValueGetter` in the Column Definition. This is similar to using a [Value Getter](./value-getters), but is specific to the filter.

{% apiDocumentation source="column-properties/properties.json" section="filtering" names=["filterValueGetter"] /%}

## Date Selection Component

By default the grid will use the browser-provided date picker for all [Supported Browsers](./supported-browsers/), but for other browsers it will provide a simple text field.
To override this and provide a custom date picker, see [Date Component](./filter-date/#custom-selection-component).

It is also possible to enable a native date picker for unsupported browsers by setting `filterParams.browserDatePicker = true`. However, you will need to test this behaviour yourself.

## Custom Selection Component

You can provide a Date Selection Component to replace the default.

The example below shows how to register a custom date component that contains an extra floating calendar picker rendered from the filter field. The problem with this approach is that we have no control over third party components and therefore no way to implement a `preventDefault` when the user clicks on the Calendar Picker (for more info see [Custom Floating Filter Example](./component-floating-filter/#example-custom-floating-filter)). Our way of fixing this problem is to add the `ag-custom-component-popup` class to the floating calendar.

{% gridExampleRunner title="Custom Date Component" name="custom-date" /%}

{% partial file="./_component-interface-javascript.mdoc" /%}
{% partial file="./_component-interface-angular.mdoc" /%}
{% partial file="./_component-interface-react.mdoc" /%}
{% partial file="./_component-interface-vue.mdoc" /%}

{% if isFramework("javascript", "angular", "vue") %}
{% interfaceDocumentation interfaceName="IDateParams" /%}
{% /if %}

## Applying the Filter

Applying the Date Filter is described in more detail in the following sections:

* [Apply, Clear, Reset and Cancel Buttons](./filter-applying/#apply-clear-reset-and-cancel-buttons)
* [Applying the UI Model](./filter-applying/#applying-the-ui-model)

## Blank Cells

If the row data contains blanks (i.e. `null` or `undefined`), by default the row won't be included in filter results. To change this, use the filter params `includeBlanksInEquals`, `includeBlanksInNotEqual`, `includeBlanksInLessThan`, `includeBlanksInGreaterThan` and `includeBlanksInRange`. For example, the code snippet below configures a filter to include `null` for equals, but not for less than, greater than or in range (between):

```js
const filterParams = {
    includeBlanksInEquals: true,
    includeBlanksInNotEqual: false,
    includeBlanksInLessThan: false,
    includeBlanksInGreaterThan: false,
    includeBlanksInRange: false,
};
```

In the following example you can filter by date and see how blank values are included. Note the following:

* Column **Date** has both `null` and `undefined` values resulting in blank cells.
* Toggle the controls on the top to see how `includeBlanksInEquals`, `includeBlanksInNotEqual`,  `includeBlanksInLessThan`, `includeBlanksInGreaterThan` and `includeBlanksInRange` impact the search result.

{% gridExampleRunner title="Date Null Filtering" name="date-null-filtering" exampleHeight=310 /%}

## Data Updates

The Date Filter is not affected by data changes. When the grid data is updated, the filter value will remain unchanged and the filter will be re-applied based on the updated data (e.g. the displayed rows will update if necessary).

## Next Up

Continue to the next section to learn about [Set Filters](./filter-set/).
